---
title: Reserve an image id and write a document with its index sidecar
summary: QueueImage end-to-end process on SAIF.Services.WCF.Services.ImagingService.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-22
operation_id: OP-012
trigger: Caller invokes `QueueImage` over the `Imaging` route.
---

# OP-012: Reserve an image id and write a document with its index sidecar

QueueImage is invoked over the `Imaging` route on `SAIF.Services.WCF.Services.ImagingService`; this page documents the process end to end, from route dispatch to the message the caller receives.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-012 |
| **Trigger** | Caller invokes `QueueImage` over the `Imaging` route. |
| **Entry operation** | [`QueueImage`](../contracts/imaging-service.md#queueimage) |
| **Owning component** | `SAIF.Services.WCF.Services.ImagingService.QueueImage` |
| **Inputs** | Request message parts listed below |
| **Outputs** | The reserved image id assigned to the queued document. |
| **Failure behavior** | Generic SOAP fault, per [Faults and error pipeline](../faults.md) |

## Request and response

| Direction | Element | Type | Declared in | Notes |
| --- | --- | --- | --- | --- |
| Request | `file` | `byte[]` | BCL (`System`) | Document bytes to persist. (Yes) |
| Request | `fileExtension` | `string` | BCL (`System`) | Extension for the persisted document; normalized to a leading `.`. (Yes) |
| Request | `imageConfig` | `ImageConfig` | External contracts assembly (`SAIF.Services.WCF.Contracts` / framework closure) ** | Imaging metadata controlling folder selection and the `.idx` sidecar content. (Yes) |
| Request | `environment` | `ApplicationEnvironment` | External contracts assembly (`SAIF.Services.WCF.Contracts` / framework closure) ** | Caller-supplied environment value; not guarded by `Enforce`. (Yes) |
| Request | `taskConfig` | `ImageTaskConfig` | External contracts assembly (`SAIF.Services.WCF.Contracts` / framework closure) ** | Optional task metadata passed through to the `.idx` sidecar; observed C# implementation signature is `ImageTaskConfig taskConfig = null` (No (C# default `null`)). SOAP-level optionality and any wire default cannot be confirmed without the external `IImagingService` contract/WSDL.** |
| Response | `long` | `long` | BCL (`System`) | The reserved image id assigned to the queued document. |

<!-- Types declared in `SAIF.Services.WCF.Contracts` are attributed to `SAIF.Framework.Core`, inferred from source and package references and marked `*`; their members are not enumerated because the external declaration was not read, marked `**`. -->

## Steps

1. Constructor resolves the Oracle `IMG` connection, evaluates `ImagingHelper.IsClaimDatabase(imagingConnectionString)` into the unused `useClaimDatabase` flag, opens the unit of work, and constructs a `FileService` ([BR-WCF-002](../business-rules.md#br-wcf-002-per-request-configuration-and-connection-resolution)).
2. `Enforce.ArgumentNotNull(file)`, `Enforce.ArgumentNotNullOrWhiteSpace(fileExtension)`, `Enforce.ArgumentNotNull(imageConfig)`; note `environment` is not guarded ([BR-WCF-023](../business-rules.md#br-wcf-023-required-arguments-are-presence-checked-before-work)).
   - On failure: `ArgumentNullException`, logged and surfaced as a generic SOAP fault.
3. `ReserveImageId()` delegates to `unitOfWork.GetRepository<Image>().GetNextImageId()`, outside any transaction, so the id is consumed even if a later step fails ([BR-WCF-024](../business-rules.md#br-wcf-024-image-id-reserved-before-any-file-write)).
4. `WriteFileWithIdx` generates a GUID file name ([BR-WCF-025](../business-rules.md#br-wcf-025-queued-image-files-are-named-by-a-fresh-guid)) and resolves `wcf.importqueuelocation`, `wcf.useobimportpriorityfolders`, and one of `wcf.lowpriorityfolder` / `wcf.medpriorityfolder` chosen by `imageConfig.SystemGeneratedFlag` ([BR-WCF-026](../business-rules.md#br-wcf-026-priority-folder-selection-for-queued-images)).
5. `EnsureFullPath` normalizes the extension to a leading `.` and the directory to a trailing `\` ([BR-WCF-027](../business-rules.md#br-wcf-027-composed-image-paths-are-normalized)).
6. Delegate to `FileService.WriteFile` to write the document bytes ([BR-WCF-004](../business-rules.md#br-wcf-004-file-operations-trust-the-caller-supplied-path)).
   > **Origin**: This step is implemented in [`WriteFile`](file-writefile.md) and executed within this operation.
7. Delegate to `FileService.WriteFile` again to write the sidecar `.idx` file containing `imageConfig.ToIDXFileString(imageId, taskConfig)` as ASCII ([BR-WCF-028](../business-rules.md#br-wcf-028-every-queued-image-gets-an-idx-sidecar)); a failure here leaves the document file present without its index.*
   > **Origin**: This step is implemented in [`WriteFile`](file-writefile.md) and executed within this operation.
8. Return `imageId`.
   - On failure: logged by the installed error handler, surfaced as a generic SOAP fault; nothing is rolled back because no transaction and no compensating delete exist.

## Process flow

The following diagram visualizes this process's control flow.

```mermaid
flowchart TD
    A["Resolve IMG connection, open unit<br>of work, construct FileService"]
    B["Validate file, fileExtension,<br>and imageConfig arguments"]
    C["Reserve next image id"]
    D["Resolve queue folder and<br>generate GUID file name"]
    E["Normalize extension and directory path"]
    F["Write document bytes to file"]
    G["Write .idx sidecar file"]
    H["Return imageId."]
    A --> B
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    G --> H
```

## Transaction and side effects

| Aspect | Finding |
| --- | --- |
| Unit of work | `OracleUnitOfWorkFactory` (`IMG`) for the id reservation; no transaction wraps the file writes |
| Commit point | Not applicable — no `Begin`/`Commit` around the file-system work |
| Records written | `Image` (id reservation only) |
| Downstream calls | File system (import queue) |
| Shared state touched | None |
| Repeat-call behavior | Each call reserves a new id and writes new files; not idempotent |

## Logging

| Surface | Written content |
| --- | --- |
| `ErrorLogErrorHandler` → `LogService` | Failure-path exception logging only, carrying method signature, calling user and exception detail; see [Faults and error pipeline](../faults.md) |

## Faults and error handling

| Failure | Fault type the caller receives | Produced by | Source |
| --- | --- | --- | --- |
| `ArgumentNullException` | `Generic SOAP fault` | The operation itself, via `Enforce` | src/WCF/SAIF.Services.WCF.Host/Services/ImagingService.cs |
| Oracle/NHibernate exception during id reservation | `Generic SOAP fault` | The `ErrorLogErrorHandler` installed by `[LogErrorBehavior]` | src/WCF/SAIF.Services.WCF.Host/Services/ImagingService.cs |
| Filesystem exception during the document or sidecar write | `Generic SOAP fault` | The `ErrorLogErrorHandler` installed by `[LogErrorBehavior]` | src/WCF/SAIF.Services.WCF.Host/Services/FileService.cs |

## Authorization

| Requirement | Enforced by | Source | Applies to |
| --- | --- | --- | --- |
| [None in code](../authentication-authorization.md#authorization-enforcement) | IIS authentication on the deployment (see [Activation and hosting](../activation-hosting.md)) | `src/WCF/SAIF.Services.WCF.Host/Services/ImagingService.cs` | This operation |

## Related documentation
- [Index](../index.md)
- [Overview](../overview.md)
- [Architecture](../architecture.md)
- [Activation and hosting](../activation-hosting.md)
- [Operations](../operations.md)
- [Faults and error pipeline](../faults.md)
- [Authentication and authorization](../authentication-authorization.md)
- [Dependencies](../dependencies.md)
- [Configuration](../configuration.md)
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [Data model](../data-model.md)
- [Operational runbook](../operational-runbook.md)
- [Tech debt](../tech-debt.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- src/WCF/SAIF.Services.WCF.Host/Services/FileService.cs
- src/WCF/SAIF.Services.WCF.Host/Services/ImagingService.cs